Program Product 


SH20-9182-1 
File No. S370-22 


VS APL for CMS: 
Installation Reference Material 


Program Number 5748-AP1 


Release 4.0 


This publication vias produced using the 
IBM Document Composition Facility 


(program number 5743-XX9) and 
the master was printed on the IBM 3800 Printing Subsystem. 


Second Edition CAugust 1982) 
This 18 a major revision of, and makes obsolete, SH20-9182-0. 


This editton applies to Release 4.0 of VS APL, Program Product 
5748-AP1, and to any subsequent releases until otherwise 
indicated in new editions or technical newsletters. 


The changes for this edition are summarized under "Summary of 
Amendments” following the preface. Specific changes are indicated 
by a vertical bar to the left of the change. These bars will be 
deleted at any subsequent republication of the page affected. 
Editorial changes that have no technical significance are not 
noted. 


Changes are periodically made to the information herein; before 
using this publication in connection with the operation of IBM 
systems, consult the latest IBM System/370 and 4300 Processors 
Bibliography, GC20-0001, for the editions that are applicable and 
current. 


Any reference to an IBM program product in this document is not 
intended to state or imply that only IBM's program product may be 
used. Any functionally equivalent program may be used instead. 


It is possible that this material may contain reference to, or 
information about, IBM products (machines and programs), 
programming, or services that are not announced in your country. 
Such references or information must not be construed to mean that 
IBM intends to announce such IBM products, programming, or 
services tn your country. 


Publications are not stocked at the address given below; requests 
for IBM publications should be made to your IBM representative or 
to the IBM branch office serving your locality. 


A form for reader's comments is provided at the back of this 
publication. If the form has been removed, comments may be 
addressed to IBN Corporation, P.Q. Box 50020, Programming 
Publishing, San Jose, California, U.S.A. 95150. IBM may use or 
distribute whatever information you supply in any way it believes 
appropriate without tncurring any obligation to you. 


© Copyright International Business Machines Corporation 1981, 


C 


TASKS THIS BOOK WILL 


This book is tntended for people who need to know how to: 

° Plan for installing VS APL 

° Install VS APL 

° Customize VS APL session manager commands and messages 
° Modify the VS APL session manager default profile 

© Specify VS APL options 


° Convert APLSV, APL\360 and APL/CNS workspaces for use under 
VS APL 


° Add auxiliary processors to VS APL 


° Create and maintain VS APL private, project, and public 
libraries 

e Transport workspaces and VS APL data files in to and out of 
CMS 


Readers should have knowledge of VS APL and the Conversational 
Monitor System (C15), including CP, ChS, and VS APL commands. 


HELP yoU DO 
This book covers the following major topics: 


"Installing VS APL” lists hardware and software requirements for 
installation, and explains: the differences batwean a shared and 
a nonshared system; how to specify a load address for shared VS 
APL; and how to specify VS APL options. This chapter also gives an 
overvier of the installation procedure anda detailed description 
of each step. 


"Customizing VS APL™ explains how to: add translate tables to 
redefine APL characters for hardcopy; specify synonyms for VS APL 
session manager commands and change the text of messages; modify 
the VS APL session manager profile; modify the APLEXIT exec; and 
specify VS APL options. 


"Converting blorkspaces to VS APL™ tells how to convert APLSV, 
APL/CHS, and APLN360 workspaces so they can be used under VS APL. 


"Defining Resources for VS APL" covers several topics, such as how 
to: define VS APL users; add auxiliary processors to VS APL; 
create and maintain private, public, and project libraries; and 
transport workspaces and VS APL data files in to and out of CilS. 


"Appendix A. Virtual Storage Requirements" contains the virtual 
storage requirements for installing and executing VS APL, and for 
executing the conversion programs. 


"Appendix B. Auxiliary Storage Requirements"™ contains the 
auxiliary storage requirements for installing VS APL. 


REQUIRED PUBLICATIONS 


You should be familiar with following publications: 


e IBM Virtual Machine Facility/370: Introduction, GC20-1800, 


provides a general description of CHS. 


What This Book is About iii 


RELATED PUBLICATIONS 


iv 


VS APL for CMS: 


IBM Virtual Machine Facility/370: CMS Command and Macro 
Reference, GC20-1818, has reference material on the syntax of 
CHS commands, EDIT subcommands, EXEC control statements, and 
CHS assembler language macro instructions. 


IBM Virtual Machine Facility/370: Edit Guide, GC20-1805, 
describes how to use the CMS editor. 


IRM Virtual Machine Facility/370: Planning and System 
Generation Guide, GC20-1801, has information on: shared 
systems; Program Level Change (PLC) commands; how to define 
3500 printer fonts; and how to define users and direct access 
storage. 
IBM Virtual Machine Facility/370: CMS User's Guide, 
GC20-1819, provides basic information about CHS and how to 
use the CMS editor to create and modify programs. 


IBM Virtual Machine Facility/370: CP Command Reference for 


Ganeral Users, GC20-1820, provides a reference for the syntax 
and usage of CP commands. 


VS APL for CMS: Terminal User's Guide, SH20-9067, describes 
how to use VS APL under CHS. 


IBM Virtual Machine Facility/370: System Programmer's Guide, 
GC20-1807, describes shared systems and how to define printer 
fonts for the IBM 3800 Printing Subsystem. 


IBM Virtual Machine Facilitv/370: Operator's Guide, 
GC20-1806, has additional information on how to define 
printer fonts for the IBM 3800 Printing Subsystem. 


You may need to be familiar with the following: 


VS APL for CMS and TSO: Writing Auxiliary Processors, 
SH20-9068, explains how to design, write, and implement 
auxiliary processors. 


VS APL for TSO: Installation Reference Material, SH20-9183, 
explains how to convert APLSV and APLN360 workspaces for use 
under TS0, and how to use the APLYUCNYV program. 


VS APL for VSPC: Installation Reference Material, 5H20-9184, 
explains how to convert APLSV and APL\360 workspaces for use 
under VSPC, and how to use the VSPC Service Program. 


VS APL for CICS/VS: Installation Reference Materiel, 
SH20-9151, explains how to convert APLSV and APLN36 
workspaces for use under CICS/VS, and how to use the CICS/VS 
Library Service Program. 


Graphical Data Display Manager (GDDM) and Presentation 
Graphics Feature (PGF) General Information, GC33-0100, has 
information on GDDM storage requirements for installation and 


on symbol sets. 


IBM Virtual Machine Facility/370: System Messages, GC20-1808, 
contains information on CP and CMS messages. 


IBM 3270 Information Display Component Description, 
GA27-2749, has information on the Program Symbol Feature for 
GRAPHPAK. 


VS APL GRAPHPAK User's Guide, SH20-9199, has information on 
the GRAPHPAK program product. 
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SYNTAX NOTATION 


NOTE ON MESSAGES 


NOTE ON TERMINOLOGY 


The following syntax notation is used in this book. 


Where an entry may take several forms, all the forms are 
indicated. When an entry is shown, a distinction is made between 
information that you must enter exactly as shown and information 
that you may supply, as appropriate. Furthermore, a distinction 
is made between APL entries and VM entries. 


If an item is representative and must be replaced with an 
appropriate value, the item will appear in underlined lowercase 
letters. 


If an APL entry is to be made exactly as shown, the entry will 
appear in APL font. For instance, in the following APL system 
command: 


)CLEAR size 


enter )CLEAR at the terminal as shown, and replace size with an 
appropriate value when you actually make the entry. 


If an entry other than an APL command is to be made exactly as 


shown, the entry Will appear in UPPERCASE unless otherwise noted. 


For instance, in the following VM command, logon is entered 
exactly as shown, while userid must be replaced: 


LOGON userid 


Entries enclosed in brackets are optional. For instance, in the 
command: 


)LOAD wsnamel? password] 


enter )LOAD at the terminal as shown; if a password is used, 


replace password with a suitable password when you actually enter 


the command. 


If a vertical line, |, separates two or more entries, choose only 
one entry. 


Where more than one option is shown and one option is the default, 


all are shown in uppercase and the default value is underlined. 


The only messages documented in this book are conversion program 
messages, Which are printed at the terminal and appear on the 
conversion report. 


Error and diagnostic messages issued by the VS APL executor are 
documented in VS APL for CMS: Terminal User's Guide. They are 
identified by a message number with the prefix "APL" and are 
printed at your terminal. You can look up VS APL messages by 
message number. 


CP and CMS messages are documented in IBM Virtual Machine 
Facility/370: System Messages. CP messages have message numbers 
with the prefix "DMK"; CMS message numbers have the prefix "DMS". 


The term "VS APL data file" refers to files created through the 
use of the VS APL Data File auxiliary processor (CAP 121). Other 
special terms are in the glossary. 


What This Book is About 
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SUMMARY OF AMENDMENTS 


VS APL RELEASE 4, AUGUST 1982 


NEW PROGRAMMING FEATURE 


Service Changes 


vi 


VS APL for CMS: 


Support for ASCII terminals, including the IBM 3101 Display and 
3232 Keyboard Printer Terminals, has been added. 


The description of the APNAMES invocation option used in 
developing and testing new auxiliary processors has been 
clarified. 


Other minor technical and editorial changes are made throughout 
the book. 
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INSTALLING VS APL 


This chapter contains: 
e The information you need for installing VS APL, such as: 


= Differences between VS APL as a shared system and asa 
nonshared system 


= Determining a load address for a shared system 
= Hardware requirements 
= Software requirements 
=e VS APL options 
e An overview of the installation procedure 


e A detailed description of each installation step 


DIFFERENCES BETWEEN A SHARED AND A NONSHARED SYSTEM 


Installing VS APL as a shared system makes better use of virtual 
storage, since several users can share one copy of the shared 
module. “Appendix A. Virtual Storage Requirements" illustrates 
the difference between the virtual machine size required for 
executing the shared system and the nonshared system. 


However, the shared system is more complicated to define than the 
nonshared system. For example, you must define one or more load 
addresses that make efficient use of virtual storage. 


Figure 1 compares the shared system with the nonshared system by 
showing where the modules reside for each system. 


If you are installing VS APL as a shared system, you should be 
familiar with the information about shared systems and saved 


seqments in IBM Virtual Machine Facilityv/370: System Programmer's 


Guide and IBM Virtual Machine Facility/4370: Planning and System 
Generation Guide. 
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Systen Shared VS APL Nonenared VS APL 


Virtual Machine Auxiliary Processors! Executor 


Interpreter 


Shared Storage Manager 


Auxiliary Processors 


Shared Storage Executor 
Interpreter 
Shared Storage Manager 


Auxiliary Processors2 


Figure 1. Differences batween the Nonshared and the Shared System: Where the Modules 


Resida 
Hotes to Figure 1 
1 Only processors not link-edited with APL. 


2 Only processors link-edited with APL. 


VS APL AS A SHARED SYSTEM: DETERNINE A LOAD ADDRESS 


If you decide to install a shared system, choose one or more 

One seament name is 
usually sufficient; the ability to define more than one segment 
name 15 provided for a shared system where users have differant 
virtual machine sizes. (For tnformation on saved segments, see 
IBM Virtual Machine Facility/370: Planning and System Generation 


segment names and associated load addresses. 


eR a A I 


Guide and IBM Virtual Machine Facility/3/70: System Programner's 


Guide,) 


Figure 2 shows the default saved segment names and the 
recommended load addresses. Define the saved segment names and 
load addresses during installation "Step 5. Build VS APL." 


Load Address 
Cin K Bytes) 


APLSYS2 1536 
APLSYS3 3534 
APLSYS4 7680 


Figure 2. Default Saved Segment Names and Recommended Load 


Addresses 


If you define more than one saved sagment name and load address 
during installation, VS APL choses the load address that makes the 
most effictent use of virtual storage for a single user. 
address depends upon the user's virtual machine size. 
example, if you define the load addresses of 1536K and 3584K 
during installation, VS APL will load the shared system at either 
address 1536K or 3584K. If the virtual machine size of a user is l 
megabyte, the shared system will be loaded at address 1536K, 
because that is the smallest load address greater than 1 megabyte. 
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You can also define saved segment names other than the default. To 
determine a load address to be associated with a saved segment 
name, follow these guidelines: 


e The address must be greater than the largest virtual machine 
of any VS APL user. 


e The address should not be unnecessarily high; if it 15, 
storage is wasted for unreferenced CP segment table entries. 


Define the segment names and load addresses during installation 

"Step 5. Build VS APL." You must also define segment names other 

than the default in the file APLSCSNT ASSEMBLE. (Sea "Step 6. VS 

APL as a Shared System: Define, Load, and Save.") 

You must not define a load address that allows V5 APL to overlap 

any other shared systems, such as the GDDM program product. 
HARDWARE REQUIRENERTS 


The following hardware is required to install and to execute V5 


APL: 

° A virtual machine large enough to install VS APL (see 
"Appendix A. Virtual Storage Requirements") 

e If you are installing a shared system, permanent space ona 


CP-owned DASD volume 


e Enough auxiliary storage to be defined as the CMS A- and Y- 
disks (see "Appendix B. Auxiliary Storage Requirements") 


° One or more of the following terminals: 
= IBM 2741 Communication Terminals 
= IBi1 3101 Display Terminals 
i IBM 3270 Display Stations 


= IBM 3767 Communication Terminals Cin 2741 migration-aid 
mode) 


= IBM 5100, 5110, or 5120 Portable Computer with the 
communication adaptor feature 


= IBM 3232 CASCII) Keyboard Printer Terminal Cunder VWM/SP 
Release 2 only) 
SOFTWARE REQUIREMENTS 
One of the following CMS systems is required: 


° VM/Basic System Extensions Program Product (BSEPP) Release 2 
(or later) 


e ice Extensions Program Product (SEPP) Release 2 Cor 
ater) 


e VM/System Program Product (VMSP) release 1 Cor later) 
You also need: 
e The VS APL installation tape 


e A Graphical Data Display Manager (GDDM) program product in 
order to use: 


= VS APL session manager 


_ GDDM auxiliary processor CAP 126) 
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- VS APL Session Manager Command auxiliary processor (CAP 
120) 


= IBM 3270 printers 


For information on GDDM program product storage requirements, 
see Graphical Data Display Manager (GDDM) and Presentation 
Graphics Feature (PGF) General Information. (If you decide to 
install GDDi1, define a load address that doesn't overlap V5 
APL.) 


The GDDM program product, the GDDM auxiliary processor, and 
the Program Symbol Feature in order to use GRAPHPAK Cfor 
information on the Program Symbol Feature, see JBM 3270 
Information Display Component Description). 


OVERVIEW OF VS APL OPTIONS 
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VS APL for CMS: 


This section describes the options you can specify during 
installation to: 


Define the CMS system and release level 

Specify whether nonsubset CMS commands can be used 
Specify whether GDDM 1s a shared or a nonshared system 
Change the filetype of: 

= Workspaces ina private library 

= VS APL data files in a private library 

= The VS APL session manager profile 


Specify the default and required minimum amount of virtual 
storage for the following: 


- The active workspace 


_ CMS commands issued through the CMS Command auxiliary 
processor CAP 100) 


= The shared storage manager 


Define auxiliary processors supplied with VS APL 
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Figure 3 explains each of the APLSCOPT parameters you can use to 
change the VS APL options. 


a 


CMSCMD! 


GDDM 


PRIVWS 


PRIVFIL 


Define the CMS system VMSP,1 See the section 

and release level. "Software 

Choices are: Requirements" for more 
information on CMS 


BSEPP,2 systems. 


SEPP,2 
VMSP,1 


Specify when CMS ALLSHR 
subset and nonsubset 
commands can be used. 
Choeices are: 

ALLSHR: Users can 
issue CMS subset and 
nonsubset commands if 
VS APL and the GDDM 
program product are 
shared, and no 
auxiliary processors 
are loaded using the 
RESAPS parameter. 
ALL: Users can issue 
CMS subset and 
nonsubset commands 
regardless of whether 
VS APL or GDDM is 
shared and any 
auxiliary processors 
are loaded. 

SUBSET: Users can only 
issue CMS subset 
commands. 


Specify whether GDDM 
1s shared, available, 
or not available. 
Choices are: 

SHARE - Shared 

YES - Available 

NO - Not Available 
Change the filetype 
suffix, WS, of 
Workspaces in private 
libraries; the suffix 
must be two 
characters. 

Change the filetype FL 
suffix, FL, of VS APL 
data files in private 
librartes; the suffix 
must be two 
characters. 


Figure 3 (Part 1 of 3). VS APL Options 
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Parar2ter Use To: Dafault Cross References 


PRIVPRO 
FRSIZE 


FRMIN 
WSSIZE 


WSMIN 
SHSIZE 


SHMIN 
SMSIZE 


Change the filetype 
suffix, PR, of the VS 
APL session manager 
profile; the suffix 
must be two 
characters. 


Specify the default 
amount of virtual 
storage for CMS 
commands issued 
through AP 100. 


65536 bytes 
(64K) 


See VS_APL for CMS: 
Terminal User's Guide 
for information on the 
FREESIZE invocation 

option. 


Specify the minimum 
reaquired amount of 

virtual storage for 
CMS support functions; 
if this amount is not 
available, VS APL is 

not initialized. 


20480 bytes 
(20K) 


12582912 bytes 
(12 Megabytes) 


Specify the maximum 
amount of virtual 
storage for the active 
workspace. 


See VS APL for CMS: 
Terminal User's Guide 
for information on the 
WSSIZE invocation 

option. 


Specify the minimun 
required amount of 

virtual storage for 
the active workspace; 
if this amount is not 
available, VS APL is 

not initialized. 


32768 bytes 
C32K) 


Specify the default 
amount of virtual 
storage for the shared 
storage manager. 


32768 bytes 
(32K) 


See VS APL for CNS: 
Terminal User's Guide 
for information on the 
SHRSIZE invocation 

option. 


Specify the minimun 
required amount of 
virtual storage for 
the shared storage 
manager; if this 
amount is not 
available, VS APL is 
not initialized. 


4096 bytes (4K) 


32768 bytes 
(32K) 


Specify the amount of 
reserved virtual 
storage for the VS APL 
session mananger; 
Cused as additional 
free space by GDDM; if 
you specified 
GDDMS=NO, speci fy 
enough storage to 
contain GDDM). 


See Graphical Data 


and Presantation 
Graphics Feature (PGF) 
General Information 
for information on 
GDDM storage 
requirements. 


Figure 3 (Part 2 of 3). VS APL Options 
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d Parameter Default Cross References 


Specify which Auxiliary See the section 

auxiliary processors processors (by "Defining Auxiliary 

are to be included in number) Processors" for a list 

the system. included: 100, of the numbers and 
101, 102, 110, names of auxiliary 
1i1l, i120, 121, processors provided. 
123, 126. 


GDMPRTY Specify the filetype ADMPRINT See GDDM User's Guide 
for GDDM print files. for a discussion of 


This matches DFTOPRTF. 

MMDDYY Specify the format of 

dates. The value YES 

causes APL to format 

dates as MM/DD/YY 

C(month/day/year); the 

value NO causes APL to 

format dates as 

DD-MiH-YY 

(day-month-year). 


the value of 
DFTOPRTF as 
_ Figure 3 (Part 3 of 3). VS APL Options 


distributed by 


GDBM. If you 
change the 
value of 
DFTOPRTF, 
change the 
value of 
GDMNPRTY also. 


Note to Figure 3 
I Some CMS commands Cparticularly commands requiring program 


storage), and user-written programs may cause VS APL to 
terminate. 
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OVERVIEW OF THE INSTALLATION PROCEDURE 


In brief, the procedure for installing VS APL under CMS is as 
follows. The procedure is described in detail in the next 
section: "Description of Each Installation Step." 

1. Log on to VM and access the A- and Y-disks. 

2 Check the files on the A- and Y-disks. 

3. Mount the installation tape. 
4 


Transfer the APLINSTL exec from the installation tape to the 
A-disk. 


Build VS APL by executing APLINSTL. 


Ul 


6. If installing the shared system: define, load, and save the 
system. 


7. Test whether VS APL is installed correctly. 

8. Define the 3800 printer fonts. 

9. If installing GRAPHPAK, define the GRAPHPAK symbol sets. 
10. If GDDM is nonshared, define GDDM modules. 


DESCRIPTION OF EACH INSTALLATION STEP 


This section describes each installation step in more detail. 


STEP 1. LOG ON TO VM AND ACCESS THE A- AND THE Y-DISKS 


8 


VS APL for CMS: 


Log on to CMS and define enough virtual storage to install VS APL: J 


DEF STOR nnnnn 
IPL CMS 


where nnnnn is the size of the virtual machine. (See "Appendix A. 
Virtual Storage Requirements" for the virtual storage 
requirements. ) 

Link to and access the system A- and Y-disks. For example: 


CP LINK userid vaddrl vaddr2 mode 
ACCESS vaddr2 A 


where 

userid 
is the identification of the directory to be searched for the 
device vaddrl. 


vaddrl 
is the virtual device address in the directory. 


vaddr2 
is the virtual device address that is to be assigned to the 
minidisk. 


mode 


is WR Cread/write). 


If the A- and Y-disks are newly allocated, format them, using the 
CMS FORMAT command: 


FORMAT vaddr Y > 
FORMAT vaddr A 


where vaddr is the virtual device address. 
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The A-disk will contain all the files transferred from the 
installation tape and the module files shown in the program 
directory. (The program directory 1s sent to you with the 
installation tape. ) 


The Y-dick will contain the generated VS APL system, and will be 
accessed by VS APL users. (Files on the Y-disk are listed in the 
program directory. ) 


For information on how to define the CMS A- and Y-disks, see IRM 


Virtual Machine Facility/370: Planning and System Generation 
Guide. 


STEP 2. CHECK THE FILES ON THE A- AND THE Y-DISK 


If the A and the Y-disks are not newly allocated, rename CMS files 
that duplicate VS APL module names listed in the program 
directory. 


To check the A- and the Y-disks for duplicate CMS file names, 
issue the ChiS LISTFILE command: 


LISTFILE * ¥ A 
LISTFILE * * Y¥ 


STEP 3. MOUNT THE INSTALLATION TAPE 


STEP 4. TRANSFER THE 


STEP 5. BUILD VS APL 


Use the CP MSG command to ask the system operator to mount the 
installation tape and to attach the tape drive as virtual device 
181, 182, 183, or 184. 


APLINSTL EXEC 


Transfer the APLINSTL EXEC (the CMS exec that builds VS APL) from 
the installation tape to the A-disk by issuing these Program Level 
Change (PLC) commands: 


VMFPLC2 REW CTAPn 
VIIFPLC2 LOAD ® ® A CTAPn 


where n is the symbolic tape identification or address of the 
device on which the installation tape 1s mounted. For information 
on PLC commands, see JBM Virtual Machine Facility/370: Planning 
and System Generation Guide. 


Determine whether you want to change the installation options. If 
so, modify the APLSOPT macro instruction in the file APLSCOPT 
ASSEMBLE and change the values for the parameters to fit your 
needs. 
The format of the macro instruction is: 

APLSOPT parmi=vall,parm2=val2,...parmn=valn 


where 


parml-parmn 
are the parameters (described in Figure 3), which can be 
specified in any order. 


vall-valn 
are the values you can specify for the parameters. 


For example, to specify a different CMS system and release level, 
change the value of the REL parameter: 


APLSOPT ...REL=C(BSEPP,2)... 
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VS APL for CMS: 


For information on the parameters, see Figure 3. 


Next, tnvoke the exec that builds VS APL by issuing the CMS 
command: 


APLINSTL 


The exec 15 conversational and prompts you for the following 
information: 


® Whether APLSCOPT has the correct options. 


° Whether this 1s the initial installation or a regeneration of 
APL. 
° The tape address of the install tape. 


e The tape density of the install tape. 


° Whether the conversion programs are to be generated. 

° Whether VS APL is to be installed as a shared or a nonshared 
system. 

° If installed as a shared system, what the saved segment name 
is. 


You can re-create a shared system at a different load address, or 
re-create the module files APL, VSAPL, APLCVCMNS, or APLCVRFQ, by 
specifying the REGEN option. If you specify REGEN, the APLINSTL 
exec: 


1. Creates the APL MODULE. 


2. Creates the VSAPL MODULE and/or does a SAVESYS for saveseq, 
where saveseg 1s the save segment name you respond with for a 
saved system. One or both of these actions will occur 
depending on what response was given to the prompts. 


3. Creates the following conversion programs Cdepending upon the 
responses to the prompts): 


° APLCVCMS MODULE 
° APLCVRPQ MODULE 


The APLINSTL EXEC performs the following actions Cif you do not 
specify the REGEN option): 


1. Transfers the required text, exec, and macro files from the 
installation tape to the A-disk. 


2. Generates the file APLMAC MACLIB. 


3. Creates the following files (depending upon the responses to 
the prompts): 


e APL MODULE (the module that determines whether a 
nonshared or a shared system is to be loaded). 


e VSAPL MODULE Cthe executor, interpreter, and shared 
storage manager for the nonshared system). 


° saveseg (where saveseg is the segment name(s) you defined 
for the shared system; the executor, interpreter, and 
shared storage manager for the shared system). VS APL 
creates saveseg only if you are installing VS APL as a 
shared system. 


e APLCVCMS MODULE Cthe conversion program for APLN360 and 
APLSV workspaces). 


Installation Reference Material 


J 


J 


C 


e APLCVRPQ MODULE Cthe conversion program for APL/CMS 
workspaces). 


STEP 6. VS APL AS A SHARED SYSTEM: DEFINE, LOAD, AND SAVE 


If installing VS APL as a shared system, define, load, and save 
the system by using the following procedure. (If not, go on to 
"Step 7. Test VS APL.™) 


ae 


Allocate permanent space on a CP-owned DASD volume to contain 
the saved system. 


Define the system to be saved by adding a NAMESYS macro to 
your installation's DMKSNT ASSEMBLE module (see IBM Virtual 


Define each seamnent name you chose in the section "VS APL as a 
Shared System: Determine a Load Address" by using the NAMNESYS 
macro. You can define four default saved segment names: 
APLSYS1, APLSYS2, APLSYS3, and APLSYS4. You can also define 
your own segment names, as explained in the section "VS APL as 
a Shared System: Determine a Load Address." The following 
example of the NAMESYS macro defines APLSYSI1: 


SYSNAME=APLSYS1, 
SYSSIZE=320K, 
VSYSADR=IGNORE, 

VSYSRES=, 

SYSCYL=, 
SYSVOL=serial-number?, 
SYSSTRT=(cylinder,page)?, 
SYSPGNM=(128-223°), 
SYSPGCT=96%, 
SYSHRSG=(8,9,10,11,12,13) 


APLSYS1 NAMESYS 


Examples of definitions for APLSYS2, APLSYS3, and APLSYS4% 
are: 


APLSYS2: SYSPGNM=(384-479) 
SYSHRSG=(24,25,26,27,28,29) 


APLSYS3: SYSPGNM=(896-991) 
SYSHRSG=(56,57,58,59,60,61) 


APLSYS4: SYSPGNM=(1920-2015) 
SYSHRSG=(€120,121,122,123,124,125) 


1The serial number of the direct access storage volume 
allocated. 


2The starting cylinder and page address for the saved 
segment. 


>The page numbers to be saved. To calculate the starting page 
number, divide the load address by @. 


*The total number of pages designated by SYSPGNM. 


More information on the NAMESYS macro is contained in IBM 
Virtual Machine Facility/370: Planning and System Generation 
Guide and IBM Virtual Machine Facility/370: System 


Proarammer's Guide. 


Assemble the new system name table, DMKSNT, by using the 
GENERATE EXEC procedure as described in IBM Virtual Machine 


Facility/3/70: Planning and System Generation Guide. 
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STEP 7. TEST VS APL 


4. Issue APLSCLNK saveseq DCSS for each saved segment. APLSCLNK 
loads the APL text decks and issues a SAVESYS command for the 
system name 'saveseg’. An example of this procedure is: 

APLSCLNK APLSYS2 DCSS 


5. Redefine your virtual machine to have a size no greater than 
the saved system's load address. 


6. If you defined saved segment names other than the default, you 
must define the segment names in a CSECT named APLSCSNT 
ASSEMBLE: 

a. Use the CMS editor to edit APLSCSNT. 


b. Add the name of each saved segment you defined: 


DC CL8'"name' 


where name is the name of the saved segment. 
c. Terminate the list: 


DC 8X'FF* END OF LIST INDICATOR 


For shared APL,» ensure that the virtual machine is smaller than 
the lowest address of the DCSS, and is at least 912K bytes. 


Enter APL and run the Installation Verification Program workspace 
by executing: 


JLOAD 2 CMSIVP 
IVP 
The IVP function prompts you for configuration information and 


produces messages telling which components are successfully 
installed. 


STEP 8. DEFINE THE IBM 3800 PRINTING SUBSYSTEM FONTS 


Use the IMAGELIB and GENIMAGE utilities to define the 3800 printer 
fonts. For information on the IMAGELIB and GENIMAGE utilities, 

see IRM Virtual Machine Facility/370: System Programmer's Guide, 
IBM Virtual Machine Facility/370: Operator's Guide, and IBM 


Virtual Machine Facility/370: Planning and System Generation 
Guide. 


STEP 9. DEFINE THE GRAPHPAK SYMBOL SETS 
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VS APL for CMS: 


If you have the Graphical Data Display Manager (GDDM) program 
product, perform the following procedure. 


GRAPHPAK includes symbol sets for the following: 
° Image characters 

° Vector graphics characters 

° Shading patterns 

To define the symbol sets: 


1. Access as your A-disk the minidisk that will contain the 
GRAPHPAK symbol sets: 


CP LINK userid vaddrl vaddr2 mode 
ACCESS vaddr2 A 
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where 


userid. 
is the identification of the directory to be searched 
for the device vaddrl. 


vaddrl. 
is the virtual device address in the directory. 


vaddr2 
is the virtual device address that is to be assigned to 
the minidisk. 


mode 
is W (Write access). 


Invoke VS APL and GRAPHPAK as follows: 


APL SHRSIZE(60K) WSSIZE(400K) 
)LOAD 2 GRAPHPAK 


Define the symbol sets as follows: 
OPENGP 


The message, APLW708&W: SYMBOL SETS DO NOT EXIST ON AUXILIARY 
STORAGE is written to your terminal; issue the commands: 


WRITESS 


OPENGP 
)OFF HOLD 


The miniditsk that contains the GRAPHPAK symbol sets should be 
available to VS APL users for read-only. See VS APL GRAPHPAK 
User's Guide for more information on GRAPHPAK. 


STEP 10. IF GDDM IS NONSHARED, DEFINE GDDM MODULES 


If GDDM is nonshared, you must define GDDM in the APLEXIT exec. 
(See Figure 3 for information on how to define GDDM as shared or 
nonshared. ) 


Use the CMS editor to modify the APLEXIT exec and add a CMS GLOBAL 
TXTLIB command to define the GDDM modules. (A comment in the 
APLEXIT exec shows where to add the command.) For information on 


the 


GLOBAL command, see JBM Virtual Machine Facility/370: CMS 


Command and Macro Reference. 


STEP 11. COPY APL EXECUTION FILES TO SYSTEM DISK 


Copy the following files to a disk accessible to users at APL 
session initiation: 


The 
who 


The 
who 


APL MODULE, VSAPL MODULE, APLIBTAB APLIBTAB, 
DEFAULT VSAPLPR, APLEXIT EXEC, and ASVPSRVC TEXT. 


following files can be placed ona disk accessible to users 
need to run the conversion programs: 


APLCVCMS EXEC, APLCVCMS MODULE, APLCVRPQ EXEC, 
and APLCVRPQ MODULE. 


following files can be placed ona disk accessible to users 
write auxiliary processors: 


APLMAC MACLIB and APLSCTBL TEXT. 
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CUSTONIZING VS APL 


This chapter explains how to tailor certain aspects of VS APL to 
fit your needs. 


You can: 

° Write translate tables to redefine APL characters for 
hardcopy 

° Define the synonyms you want for VS APL session manager 


commands 
e Change the text of VS APL session manager messages 


e Modify the VS APL session manager default profile to change 
the VS APL session manager settings 


e Modify the APLEXIT exec 


e Specify VS APL options 


REDEFINING VS APL CHARACTERS FOR HARDCOPY 


When APL characters are sent to a hardcopy destination, they are 
translated to EBCDIC. You can write your ovn translate tables to 
redefine the EBCDIC characters. The following translate table, 
for example, suppresses line control characters, but all other 
characters remain the same. 


x 0123456789 ABCODE F 
DC X"'40404040404040404040404040404040' 
DC X'40404040404040404040404040404040' 
DC X'40404040404040404040404040404040' 
DC X'40404040404040404040404040404040' 
DO X'404142434445464748494AGB4C4D4E4F" 
DC x15 05152535455565758595A5B5C5D5E5F* 
DC X'6061626364656667686 I6A6B6CEDEEGF' 
DC X'707172737475767778797A7B7C7D/E7F* 
DC X'8081828384858687888 SSASBSCEDSESF * 
DC X"909192939495969798999A9B9CIDIEDF' 
DC X'ADALAZASASA5AGATABASAAABACADAEAF' 
DC X'BOBIBZB3IB4B5B6B7 B8B9BABBBCBDBEBF * 
DC X'COCIC2C3C4C5CECTC8CICACBCCCDCECF' 
DC X'D0D1ID2ZD3D4D5D6D7D&8DIDADBDCDDDEDF * 
DC X'EQELEZESE4E5E6E7E8ESEAEBECEDEEEF' 
DC X'FOFLF2F3F4F5F6F/7F8F9FAFBFCFDFEFF* 


AMIOWOEPwoenyruwnoune oe 


See VS APL for CMS: Terminal User's Guide for information on the 
default translation of APL to EBCDIC. Follow these guidelines for 
writing a translate table: 


6 The program name must be APLXxxxx, where xxxx is a 4-digit 
number. 


e Assemble the translate table and place the load module on the 
Y-disk. Users can obtain the translation by specifying the 
name of the translate table as the COPY value in their VS APL 
session manager profile. (See VS APL for CMS: Terminal User's 
Guide for more information on the COPY command. ) 
CUSTOMIZING THE VS APL SESSION MANAGER 


The VS APL session manager enables you to use a set of commands to 
control your VS APL session. For example, you can: 


e Display only the portions of your scroll file you want to see 
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e Define or display PF key settings 
e Produce a continuous copy of your terminal session 
e Query the current setting of any of the commands 
For a complete description of the VS APL session manager commands 
and messages, see VS APL for CMS: Terminal User's Guide. 
HOW TO DEFINE SYNONYMS FOR CONNANDS AND CHANGE THE TEXT OF MESSAGES 


You can customize the VS APL session manager by defining synonyms 
for commands and by changing the text of messages. 


1. Edit the APLACMSG module; the module has the following 


statements: 
APLACMD 
END 
° To define a synonym for a command or keyword, modify the 


APLACND macro instruction. The format of the macro 
instruction 1s: 


APLACMD cmdl=-usercmdl ,cmd2=usercmd2,...cmdn=usercmdn 


where 


cmdl-cmdn 
are VS APL session manager commands or parameters 
truncated to their initial seven characters: 


CODE 
COLUMN 
COPY 
DEFAULT 
DELAY 
DISPLAY 
EDS 
HELP 
HOLD 

ID 
IMMEDIATE (specify as IMMEDIA) 
LINE 


PROFILE 

RENUMBER (specify as RENUMBE) 
SAVE 

SCREEN 

SIZE 

SUPPRESS (specify as SUPPRES) 
WRAP 


For a description of the VS APL session manager commands 
and keywords, see VS APL for CMS: Terminal User's Guide. 


usercmdl-usercmdn 
are the command or keyword names you define. 


Do not define a synonym that is: 2 

- The same as any other command, keyword, or synonym. 
Two of these words are considered the same if their 
first 8 characters are identical. 


= Longer than 12 characters. 
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-_ An abbreviation for a command or keyword. For 


example, do not define a synonym of CO for the command 
COLUMN, since CO could also be an abbreviation for 
the command COPY. (The VS APL session manager allows 
you to abbreviate commands and parameters, if the 
abbreviations are unique.) 


For example, to redefine the VS APL session manager 
command, LOG, as SCROLL», modify the APLACMD macro 
instruction as follows: 


APLACMD LOG=SCROLL 
END 


To change the text of a message, add the following macro 
instruction to the APLACNMSG module: 


APLAMSG MSGID=APLMnnnc,MSGTEXT='text 
of messaqea’ 


where 


nan 


is the message number. 


la 


1s the message level: 


- Eventual Action 
- System Wait 

- Information 

- Immediate Action 


>HEm 


text of message 


is the text you define for the message. The length of 
the text may not exceed 60 characters. 


For example, to change the VS APL session manager 
message, APLN423E NOT ENOUGH FREESPACE, to APLIIG23E 
INCREASE FREESPACE AND TRY AGAIN, add the following to 
the APLACNSG module: 


APLACMD 

APLANSG MSGID=APLM423E, 
MSGTEXT="INCREASE FREESPACE AND 
TRY AGAIN' 

END 


Assemble the APLACMSG module. 
Invoke the APLINSTL exec: 


APLINSTL 


Specify the REGEN option when prompted to. 


HOW TO MODIFY THE DEFAULT PROFILE 


VS APL for CMS: 


The VS APL session manager profile defines some settings of the VS 
APL session manager commands. It 1s copied during installation to 
the Y-disk. You can modify the profile and change the default 
settings by using the CMS editor. The file identification is: 


DEFAULT VSAPLPR xX 
where * is any filemode. 
VS APL for CMS: Terminal User's Guide tells how to create new VS 
APL session manager profiles. (Other profiles you define override 


the default profile when they are used.) VS APL session manager 
settings are also described in the Terminal User's Guide. 
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For information on how to use the CMS editor, see IBM Virtual 
Machine Facility/Z370: Edit Guide. 


SS RT I 


MODIFYING THE APLEXIT EXFC 


The APLEXIT exec is invoked to define CMS and CP settings when VS 
APL 15 initialized and to restore the CMS session at the end of an 
APL session. You can modify the APLEXIT exec to, for example, 
allow messaces to be printed to your terminal during your VS APL 
session. Also, you can use the APLEXIT exec to protect against a 
possible loss of CHS storage when dynamically loading auxiliary 
processors using the APNATIES invocation option. For a discussion 
of this latter use of the APLEXIT exec, see the "Defining 
Auxiliary Processors" section below. 


To modify the APLEXIT exec, edit the file: 
APLEXIT EXEC 


lt TLS LS a Ne 


Facility/370: CMS Command and Macro Reference. 


SPECIFYING VS APL OPTIONS 


NE 


To specify VS APL options, do the following: 

i, Edit the APLSCOPT module and modify the APLSOPT macro 
instruction, changing the values for the paramaters. The 
macro instruction format is: 

APLSOPT parml=vall,parmé@-val2,...parmn=valn 


where 


parml-parmn 
are the parameters (described in Figure 3), which can be 
specified in any order. 


vali-valn 
are the values you can specify for the parameters. 


For example, to indicate that GDDM is not available, change 
the value of the GDDM parameter: 


APLSOPT ...GDDM=NO... 
2. Assemble the APLSCOPT module. 
3. Invoke the APLINSTL exec: 
APLINSTL 


Specify the REGEN option when prompted to. 
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ERTING WORKSPACES TO VS APL 


This chapter explains how to convert APL\360, APLSV, and APL/ZCHS 
Workspaces so you can use them under VS APL. There is no need, 
however, to convert workspaces from previous releases of VS APL to 
VS APL Release 4. The following topics are covered: 


e Planning for conversion, such as how to identify and change 
invalid library numbers and workspace names, and how to plan 
the auxiliary storage 


° Conversion input 
e An overview of the conversion procedure 
e A detailed description of each conversion step 


PLANNING FOR CONVERSION 


This section explains how to change input workspace 
identifications that are invalid for CliS and how to plan the 
auxiliary storage you use for converting workspaces. 


HOW TO IDENTIFY AND CHANGE IHVALID LIBRARY NUNBERS AND HORKSPACE NAMES 


CMS does not accept: 
® Library numbers with more than seven digits 


e A workspace name that contains deltas, underscored letters, 
lowercase letters, or national characters 


e A workspace name longer than eight characters 


You should have the workspace owner modify these items before the 
workspace is dumped to tape. Modifying these items Esfore, rather 
than during, the conversion procedure will simplify the 
procedure. 


If unacceptable items still remain, use the conversion program 
RENANE option during conversion to change library numbers or 
workspace names. You can also use the IGNORE option to not convert 
a workspace at all. (These options are described in "Step 5. 
Interact with the Conversion Program.") 


PLANNING AUXILIARY STORAGE 
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VS APL for CMS: 


The auxiliary storage you require differs, depending on whether 
you are converting: 


e APL“CMS, APL\360, or APLSV workspaces for use under CMS. for 
use under CMS You need A-disk space; the APLCVRPQ or the 
APLCVCHS conversion program transfers the converted 
workspaces to your A-disk. 


e APL/“CMNS workspaces for use under CICS/VS, VSPC, or TSQ0O. You 
need both A-disk space and a scratch tape. The APLCVRP 
conversion program transfers the converted workspaces to the 
scratch tape and creates two JCL files on your A-disk. 


Estimate the amount of auxiliary storage required according to 
the number of workspaces to be converted, their size, and the 
amount of data they contain. Use an A-disk with sufficient space 
for all the workspaces to be converted. CIf you do not have a 
large enough A-disk, the conversion program gives you a message 
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, and terminates; you can define more auxiliary storage and restart 
the conversion program. ) 


Input to the conversion procedure is a conversion tape containing 
a dump of the workspaces to be converted. It +5 possible to have 
more than one tape, and workspaces can span two volumes. 


To produce a conversion tape for APL/CMS workspaces, issue the CMS 
TAPE DUSiP command. The tape should only contain workspaces that 
were created on Version 2 of APL/CHMS. 


You can obtain conversion tapes containing APLSV or APLN369 
workspaces from a CICS/VS or VSPC installation. 


OVERVIEN OF THE CONVERSION FROCEDURE 
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The conversion procedure differs, depending on the source of the 
Workspaces and the destination. 


You can convert: 
° APL/CMS workspaces for use under CMS (see Figure 5) 


e APL/CMS workspaces for use under VSPC, CICS, or TSO (see 
Figure 6) 


° APLSV or APLN360 Workspaces for use under CMS (see Figure 7) 


Figure 4 shows which CMS program converts workspaces for use 
under different subsystems. For information on converting APLSV 
or APL\N360 workspaces for use under CICS/VS, TSO, or VSPC, see VS 

( APL for CICS/VS: Installation Reference Material; VS APL for TSO: 
Installation Referance Material; or VS APL for VSPC: Installation 
Reference Material. 


Workspace Program Used to Convert for: 

Source cIcssVvs CHS TSO VSPC 
APLSV — APLCVCMS — — 
APL\360 — APLCVCMS — — 
APL/CHS APLCVRPQ APLCVRPQ APLCVRPQ APLCVRPQ 


Figure 4. CMS Programs Used to Convert Workspaces 

In general, the steps for converting workspaces to VS APL are: 

1. Log on to VM. 

2 Access the A-disk. 

3. Mount the conversion tape. 

4 Invoke the conversion program: APLCVCMS if converting APLSV 
or APLN360 workspaces; APLCVRPQ 1f converting APL/CMS 


workspaces. 


5. Interact with the conversion program; specify workspace names 
and library numbers. 


6. Change the identification of workspaces for use under CMS. 


7. Distribute converted workspaces and the conversion report 
according to the destination of the workspaces. 
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Figure 5. Converting APL/CMS Workspaces for Use under CMS 
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Figure 6. Converting APL/CMS Workspaces for Use under VSPC, CICS/VS, or TSO 
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Figure 7. Converting APLSV or APLN360 Workspaces for Use under CMS 
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DESCRIPTION OF EACH CONVERSION STEP 
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STEP 1. LOG ON 


This section describes each step for converting a workspace to VS 
APL. 


Log on to VM and issue these CP commands: 


DEF STOR nnnnn 
IPL CMS 


where nnnnn 1s the virtual machine size. Be sure you have enough 
virtual storage to execute the conversion program (see "Appendix 
A. Virtual Storage Requirements"). 


STEP 2. ACCESS THE A-DISK 


Link to and access for read/write the A-disk that you identified 
in "Planning Auxiliary Storage." If the A-disk is newly 
allocated, format it using the CMS FORMAT command: 


FORMAT nnn A 


where nnn 1s the virtual device address. 


STEP 3. MOUNT THE CONVERSION TAPE 


Issue the CP MSG command and ask the system operator to mount the 
conversion tape (or the first one if you have more than one tape). 
Have the operator attach the tape drive as virtual device 181. If 
you are converting APL/CMS workspaces for use under VSPC, 
CICS/VS, or TSO, ask the system operator to also mount a scratch 
tape as virtual device 182. 


STEP 4. INVOKE THE CONVERSION PROGRAM 


Invoke the conversion program to convert APLSV or APLN360 
Workspaces by using the following command: 


APLCVCMS [CFULL|RESUME|SELECT] 
CCONTENT|NOCONTENT] 


To convert APL/CHS workspaces, use: 
APLCVRPQ [TFULL]RESUME]? [CCONTENT|NOCONTENT] 
The options are as follows: 
° FULL: all workspaces on the tape are converted to VS APL. 


° RESUME: all workspaces, beginning with a specified workspace, 
are converted. (Specify the workspace identification during 
"Step 5. Interact with the Conversion Program."™) 


° SELECT: only specified workspaces are processed. (Specify the 
identification of the workspaces to be converted during "Step 
5. Interact with the Conversion Program.") Notice that you 
can not use the SELECT option with APLCVRPQ. 


e CONTENT: workspaces and function statements are converted to 
VS APL format. Content conversion examines function 
statements that may not execute under VS APL and converts them 
to their VS AP equivalent, if there is one. Function 
statements that are not converted are listed in the 
conversion report, so that users can change them. 
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e NOCONTENT: workspaces are converted to VS APL, but functions 
are neither converted to their VS APL equivalent, nor 
included in the conversion report. 


The default options are FULL and CONTENT. 


STEP 5. INTERACT WITH THE CONVERSION PROGRAM 


The conversion procedure is conversational; enter information 
when you are prompted. 


Representing APL Characters with EBCDIC Characters 


When entering workspace identification in response to conversion 
program prompts, represent APL characters with EBCDIC (Figure 8): 


Figure 8&8. EBCDIC Representation of APL 


When the conversion program displays a workspace identification 
as part of a prompt, it uses the EBCDIC representation for APL 
characters shown in Figure 8. 


Responding to Conversion Program Prompts 
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Respond to the following prompt: 
IS OUTPUT FOR VSPC CYESINO) 


Enter YES if the workspaces are intended for VSPC, CICS/VS, or 
TS0; enter NO, if otherwise. 


The conversion program prompts for the numbers of libraries and 
names of workspaces to be converted Cunless you specified FULL as 
a conversion option). 


If you chose RESUME in "Step 4. Invoke the Conversion Program," 


specify the identification of the workspace at which conversion 
is to begin in response to the prompt, WSID: 


library-number workspace-name 


If you chose SELECT, specify the identification of a workspace to 
be converted in response to each prompt, WSID: 


e Either: 
library-number workspace-name 
to select a specific workspace. 
© Or: 
library-number 


to select all workspaces ina library. 
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Press the RETURN key (the ENTER key if you are using an IBM 3270 
Display Station) after each entry. To terminate the list, press 
the RETURH key or the ENTER key twice. You can specify up to 100 
entries. Morkspaces in the list that are not found on the input 
tape are ignored. 


Changing Invalid or Durlicate Uorkcpace Nanes and Library Numbers 


If a workspace identification on the conversion tape 1s invalid 
(see "How to Identify and Change Invalid Library Numbers and 
Workspace Names"), the conversion program prompts you for one of 
the following options: 


e RENAME: To give the workspace a new name. Specify the new name 
in response to the prompt, CIS FILENAME. Specify the new 
library number in response to the prompt, CNS FILETYPE. Press 
the RETURN key Cor ENTER key for IBM 3270 Display Stations) 
alone to leave either one unchanged. 


e IGNORE: To not convert the workspace. 
If you do not choose either of these options, the conversion 


program does not convert workspaces with invalid names or library 
numbers. 


If an identification duplicates the identification of a file on 
the A-disk, the conversion program prompts you for one of the 
following options: 


e RENAME: To give the workspace a new name. Specify the new name 
in response to the prompt, CMS FILENANE. Specify the new 
library number in response to the prompt, CMS FILETYPE. Press 
the RETURN or ENTER key alone to leave either one unchanged. 


e REPLACE: To replace the CNS file on the A-disk with the 
workspace to be converted. 


® IGNORE: To not convert the workspace. 
e CANCEL: To terminate the conversion program. 
If you do not choose one of these options, the conversion program 
replaces the CMS file with the workspace. 
Restarting the Conversion Program 


AT THE END OF THE TAPE: When the end of the conversion tape or the 
scratch tape 1s reached: 


° Either enter CANCEL to terminate the conversion program 
° Or continue on to the next tape: 


1. Enter CP mode by pressing the ATTN key twice (or press the 
PAL key if you are using an IBM 3270 Display Station). 


2. Use the CP MSG command to ask the system operator to mount 
the next tape on the tape drive. 


3 Type the CP BEGIN command. 
4. Type RESTART. 


BECAUSE OF UNEXPECTED TERMINATION: If the conversion program 
terminates because the A-disk is full, or beacause of some 
unrecoverable error, the last partially converted workspace is 
erased from the A-disk. Its identification is printed at the 
terminal. Complete the procedure for the converted workspaces by 
performing the last two steps of the conversion procedure. 
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Process the partially converted workspace and others not yet 
converted by following these steps: 


1. Rewind the conversion tape by issuing this CMS command: 
TAPE REbl 
2. Make sure that you have enough A-disk space. 


52 Invoke the conversion program again. Specify the RESUME 
option and the identification of the workspace that was named 
when the conversion program terminated. If you want to 
specify that individual workspaces be converted, use the 
SELECT option; be sure to specify the identification of the 
Workspace that was named when the conversion program 
terminated. 


STEP 6. CHANGE CONVERTED HMORKSPACE IDENTIFICATION FOR USE UNDER Ci 


If you are converting workspaces for use under CMS, you should 
change the filetype of all private workspaces and of APL/CMS 
public workspaces to make the converted workspace identification 
consistent with VSAPL identification. 


How the Conversion Program Chaness Worksnpece Identification 


Mhen an AFLNZ69 or APLSV workspace is converted, the conversion 
program changes the identification to a ChiS file identification. 
The workspace name, truncated from the right to eight characters, 
becoreas the CNS filename. The library number becomes the CIis 
filetype. It ts truncated from the left to seven digits,» or 
extended to the left with zeros to seven digits, and prefixed with 
aW. The CMS filemode is always Al. For example: 


Workepace Identification CHS File Idcntificaticn 


25 GENWORK | GERHMORK WO000025 Al 


1234567 COMPUTATION COMPUTAT W1234567 Al 


12345678 XREF XREF W2345678 Al 


Figure 9. How the Conversion Program Changes Workspace 
Identification 


When an APL/CHS workspace is converted, the conversion program 
doesn't change its identification. The filetype of a private 
APL/CMS workspace is VIIAPLWS. The filetype of public APL/CHS 
workspaces is Pnonnnnnn, where nnonnnnn is the library number. You 
have to change the filetype of private and public APL/CHS 
workspaces (see the next section, "Changing Converted Workspace 
Identification,” for how to do this). 
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VS APL for CMS: 


You can either change workspace identifications before you 
distribute the workspaces, or let the Workspace owners make the 
changes. 


To change workspace identification yourself: 

° Change the filetype of all private workspaces to VSAPLWS. Use 
the CMS editor to create the NEWTYPE EXEC, containing these 
statements: 

&CONTROL ERROR 
RENAME &1 &2 &3 = VSAPLWS = 
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Use these commands to change the workspace filetypes: 


LISTFILE * filetyne ACEXEC 
CMS NENTYPE 


where 


filetype 
of APLSV and APL\360 workspaces 15 Wnnnnnnn, where 
nonnnnn is the library number of one owner's workspaces. 
In the case of APL/CMS, filetype is VMAPLWS. 


Distribute all the APLSV and APLN360 workspaces for one owner 
before changing any more filetypes. For how to do this, see 
"Step 7. Distribute Converted Workspaces and the Conversion 
Report.” 


e Change the filetype of APL/CMS public workspaces to Wnonnnnnn, 
where nnnnnnn is the source APL library number. Issue the 
REHATIE command for each public workspace: 


RENAME * Pnnnnnnn A = Wnnnonnn = 


e Change lowercase Letters or national characters in APL/CMS 
file identifications to uppercase letters or numbers. 


STEP 7. DISTRIBUTE CONVERTED WORKSPACES AND THE CONVERSION REPORT 


FOR USE UNDZR CNS: To distribute Workspaces intended for use under 
CMS, follow these steps: 


@ If the workspaces are APL/CNS, issue these commands for each 
workspace: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 
ERASE filename filetype 


where 


userid 
is the owner's user identification. 


filename filetype 
is the identification of the APL/“CMS workspace. 


e If the workspaces are APL\360 or APLSV, issue these CMS 
commands: 


SPOOL PUNCH userid 
LISTFILE * filetype ACEXEC 
CMS DISK DUTIP 

ERASE * filetype aCEXEC 


where 


userid 
is the owner's user identification. 


filetype 
either VSAPLWS for a private workspace or Wnnnnnnn 
roa public workspace. 


ou 


Separate the conversion report into sections by Library number 
and distribute the sections to their owners. It is a good idea to 
also stress the importance of reading the conversion report, 
since the report indicates conversion errors and problems which 
the workspace owner should correct. 


FCR USE UNDER CICS/VS OR VSPC: To complete the conversion 


procedure, send the converted workspaces (Con the scratch tape), 
the two JCL files CIMPORT DDCARDS and IMPORT COMMANDS on your 
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A-disk), and the conversion report to the CICS/VS or VSPC 
installation. 


At a CICS/VS installation, the workspaces will be used as input to 
the IMPORT function of the APL Library Service Program; at a VSPC 
installation, they will be used as input to the VSPC Service 
Program. The JCL files will be used to run either the APL Library 
Service Program or the VSPC Service Program. 


Before distributing the workspaces, you should modify the JCL 
files on your A-disk. The IMPORT DDCARDS file contains the DD 
statement for each converted workspace: 


//ddname DD DSN=wsname, UNIT=2400,LABEL=Cp,NL), 


// VOL=SER=XXXX, DISP=COLD,PASS), 

// DCB=C(CLRECL=80,BLKSIZE=*%,RECFM=FBS) 
where 
ddname 


is M1 through Mn, where n is the total number of converted 
Workspaces. 


wsname 


1s the workspace name (the CMS filename). 


is the position of the workspace on the output tape. 


The file IMPORT COMMANDS contains the IMPORT statement for each 
converted workspace. 


IMPORT wsname FROMCddname) TYPECOBJECT) CONTENTCAPL) 
where wsname is the workspace name. 
Use the CMS editor to make modifications to the JCL files: 


° If you are sending the workspaces to a CICS/VS installation, 
add the JCL statements required by the APL Library Serivice 
Program. (See VS APL for CICS/VS: Installation Reference 
Material for more information on what JCL to specify.) If you 
are sending the workspaces to a VSPC installation, add the JCL 
statements required by the VSPC Service Program. (See VS APL 
for VSPC: Installation Reference Material.) 


° For both CICS/VS and VSPC: Add an AUTH control statement for 
each set of library numbers specified in the IMPORT COMMANDS 
file. The AUTH control statement identifies the user level of 
authorization. (See VS APL for CICS/VS: Installation 
Reference Material for more information on the APL Library 
Service Program AUTH control statement. See VS APL for VSPC: 
Installation Reference Material for more information on the 
VSPC Service Program. ) 


° Make the following modifications to the file IMPORT DDCARDS: 


= For each DD statement, change XXXX to the serial number of 
the output tape. 


= For CICS/VS, change the DCB to 
CLRECL=800,BLKSIZE=800,RECFM=F). 


= If the output tape has standard labels, change the LABEL 
subparameter NL in each DD statement to SL. 


oa If the host system is DOS/VS and LABEL is specified in the 
ENVIRONMENT statement, use the information in the IMPORT 
DDCARDS to prepare the required TLBL statements. 


_— Change lowercase letters or national characters ina 
Workspace name to uppercase letters. 
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CONVERSION MESSAGES 


e Make these modifications to the file IMPORT COMMANDS: 


= If the workspaces are to be transferred to APL libraries 
other than those specified in the AUTH control statement, 
insert the library number in each IMPORT statement. 


= For CICS/VS: Delete TYPECQBJECT) and CONTENTCAPL?) from 
each IMPORT card. 


_ Change lowercase letters or national characters in 
workspace names to uppercase letters or numbers. 


Print and punch the JCL files by itssuing these CMS commands: 


PRINT IMPORT DDCARDS 
PRINT IMPORT COMMANDS 
PUNCH IMPORT DDCARDS 
PUNCH IMPORT COMMANDS 


Send the scratch tape, the conversion report, and the printed and 
punched JCL files to the CICS/VS or VSPC installation. 


FOR USE UNDER TSO: Send the converted workspaces on the scratch 
tape and the conversion report to the TSO installation. 


The followWing error messages are printed at the terminal and 
appear in the conversion report. Additional messages appear in 
the conversion report. For a list of these, see VS APL for CMS: 


Terminal User's Guide. 


e HDR LABEL I70 ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input 
header label was being read. 


System Action: Terminates execution of the conversion 
program. 


User Action: Obtain another copy of the conversion tape. 
Program issued by: APLCVCMS 
e TRLR LABEL I/O ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input 
trailer label was being read. 


System Action: Terminates execution of the conversion 
program. 


User Action: Do nothing, if the error occurred on the last or 
only volume. Otherwise, run the conversion program again, 
using the remaining volumes. 


Program issued by: APLCVCMS 
° SYSTEM ERROR WHILE CONVERTING WORKSPACE/ DIRECTORY 


libnum wsname. WORKSPACE/DIRECTORY UNCONVERTED AND PRESUMED 
DAMAGED 


Explanation: A program check occurred, probably because of 
invalid information in a workspace or directory. 


System Action: Prints the contents of the program check, old 
PSW, and general registers. Conversion continues with the 
next workspace. 


User Action: Obtain another copy of the rejected workspace or 
library. 
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VS APL for CMS: 


Program Issued By: APLCVCMS or APLCVRPQ 
ERROR UNRECOVERABLE. CONVERSION ABORTED 
Explanation: Repeated system errors have occurred. 


System Action: Prints a storage dump, and terminates 
execution of the conversion program. 


User Action: Obtain another copy of the input tape. 
Program issued By: APLCVCMS or APLCVRPQ 
WORKSPACE REJECTED, NOT CONVERTED DUE TO I/40 ERROR 


Explanation: An unrecoverable error occurred while the 
workspace was being read. 


System Action: Continues execution of the conversion program 
with the next workspace. 


User Action: Obtain another copy of the rejected workspace. 
Program Issued By: APLCVCMS or APLCVRPQ 

WORKSPACE FULL 

Explanation: The workspace is too large to be converted. 


System Action: Continues execution with the next object in 
the workspace. 


User Action: Have the owner of the workspace compress it or 
split it into two workspaces and obtain a dump of the modified 
workspace. 


Program Issued By: APLCVCMS 


WRITE ERROR nn WHILE SAVING Libnum wsname. CONVERSION 
CANCELLED 


Explanation: The FSWRITE macro returned an error code. nnis 
the return code. (See IBM Virtual Machine Facilitv/370: 


Command Lanauage Guide for General Users.) Probable cause of 
the error is a full A-disk Creturn code 13). 


System Action: Terminates execution of the conversion 
program. 


User Action: Determine the reason for the error, and correct 
it. Then run the conversion program again, specifying the 
RESUME option and the identification of the rejected 
workspace. 


Program Issued By: APLCVCMS 
IMPORT FILE SEQUENCE NUMBER nnnn 


Explanation: Displays the file sequence number nnnn of the 
converted workspace filename filetype on the output tape. 


System Action: None. 


User Action: Use the information when preparing the service 
Program control statements for CICS/VS or VSPC. 


Program Issued By: APLCVRPQ 
NOT A CMS DUMP TAPE. CONVERSION CANCELLED 


Explanation: The input tape is not a CMS dump tape. 


Installation Reference Material 


System Action: Terminates execution of the conversion 
program. 


User Action: Mount the correct tape. 
Program Issued By: APLCVRPQ 
NOT AN APL/CMS CPRPQ) WORKSPACE 


Explanation: The file is not an APL/CMS workspace. 


System Action: Continues execution of the conversion program 


with the next file. 


User Action: None necessary, unless all the files on the tape 


are rejected. If so, mount the correct tape. 
Program Issued By: APLCVRP@Q 
INADEQUATE SPACE TO RUN CONVERSION. CONVERSION CANCELLED 


Explanation: There is less than 64K bytes of free virtual 
storage space available. 


System Action: Terminates execution of the conversion 
program. 


User Action: Define a larger virtual machine. 
Program Issued By: APLCVRPQ 
filename filetype WORKSPACE TOO LARGE FOR VIRTUAL MACHINE 


SIZE. RERUN WITH LARGER MACHINE. WSSIZE IS xxxx. NEED ABOUT 
yyyvy BYTES TO CONVERT. 


Explanation: The workspace is too large to be converted. 


System Action: Terminates execution of the conversion 
program. 


User Action: Define a larger virtual machine. 


Program issued by: APLCVRPQ 


filename filetype WORKSPACE DAMAGED OR INVALID. NOT CONVERTED 


Explanation: Either internal pointers in the workspace are 
invalid, or the workspace is not Version 2. 


System Action: Continues execution of the conversion program 


With the next Workspace. 
User Action: Obtain a valid copy of the rejected workspace. 


Program Issued By: APLCVRPQ 
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DEFINING RESOURCES FOR VS APL 


This chapter explains how to: 


Define new VS APL users to the Control Program (CP) 
Define new auxiliary processors 
Create and maintain public and project libraries 


Transport VS APL workspaces and VS APL data files in to and 
out of CMS. 


DEFINING VS APL USERS TO CP 


Under CP, a VS APL user is a CP user who has access to the VS APL 
libraries. To define a directory entry for a VS APL user, follow 
these guidelines: 


Because the user's A-disk is a VS APL private library, define 
the minidisk with enough space for anticipated workspace 
storage. See the section "Appendix B. Auxiliary Storage 
Requirements." 


Because the Y-disk contains the VS APL public libraries, 
define it as read-only in the user's directory entry. 


Do not Link to the project library disks, since VS APL links 
dynamically to them. 


See IBM Virtual Machine/370: Planning and System Generation Guide 
for information on how to define a user to CP. 


DEFINING AUXILIARY PROCESSORS 


Under CMS, an auxiliary processor is a CMS file with the filename 
used to invoke it, a filetype of TEXT> and any filemode acceptable 
to CMS. 
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VS APL for CMS: 


You can define: 


User-written auxiliary processors 


Auxiliary processors provided with VS APL and not defined 
during installation 


To define a user-written auxiliary processor: 


Les 


Assemble the auxiliary processor, using the CMS ASSEMBLE 
command. 


Use the CMS editor to edit the APLSCOPT module and to modify 
the APLSOPT macro instruction. Add the auxiliary processor 
number to the list of auxiliary processors defined by the 
RESAPS parameter. For example, to add a new auxiliary 
processor 600 to your system: 


APLSOPT RESAPS=C...600) 


You can specify up to 15 auxiliary processors with the RESAPS 
option. 


Assemble the APLSCOPT module. 
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4. Modify the APLSCLNK EXEC on your A-disk by adding the name of 
the text file. For example, if you are adding new auxiliary 
processor AP 600, the INCLUDE statement should look like 
this: 


INCLUDE APL100 APL1IO1 APL110 APL111 APL120 APL121 APL123 
APL126 APLE00 


The auxiliary processor numbers can be in any order. 


VS APL for CMS and TSO: Mriting Auxiliary Processors describes how 
to desian, write, and test auxiliary processors. 


To define an auxiliary processor supplied with VS APL: 

1. Edit the APLSCOPT module and modify the APLSOPT macro 
instruction, adding the number of the auxiliary processor to 
the list defined by the RESAPS parameter. For example, to 
define the VSAM auxiliary processor CAP 123): 

APLSOPT RESAPS=C€...123) 

2. Modify the APLSCLNK EXEC on your A-disk by adding the name of 
the text file. For example, to define the VSAM auxiliary 
processor (CAP 123), modify the INCLUDE statement in the 
APLSCLHNK EXEC as follows: 


INCLUDE APLi100 APL101 APL110 AP111 APL120 APL121 
APL126 APLI23 


The auxiliary processors provided with VS APL include: 
° AP 100: Command Processor 
° AP 101: Alternate Input 
° AP 110: CMS File 
° AP 111: QSAM 
° AP 120: VS APL Session Manager Command 
° AP 121: VS APL Data File 
e AP 123: VSAM 
© AP 126: Graphical Data Display Manager 
Assemble the APLSCOPT module. 
Invoke the APLINSTL exec: 
APLINSTL 


Specify the REGEN option when prompted. 


For Use by Only One VS APL User 
VS APL users can define auxiliary processors for use under their 
APL sessions by using the APNAMES invocation option to specify the 
auxiliary processor. For example, if a user invokes VS APL with 
the following option: 
APL APNAMESCAPL600) 
auxiliary processor 600 can be used under that user's APL session. 


You can specify a maximum of 15 auxiliary processors with the 
APNAMES option. 
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Mote: There is a slight possibility of losing CMS storage when 
loadina an AP using the APHANES invocation option. To avoid this 
possibility, edit the APLEXIT exec prior to loading your AP that 
uses APHAMES. Add this line to the APLEXIT exec: 


LOAD DIMSZIT CHOMAP 


If you have not modified the APLEXIT exec, using APNAMES can 
possibly cause a CIIS storage loss in the following way. If you 
enter APL and load your AP using the APNANES invocation option, 
your AP is put in the CMS GETMAIN storage area by means of the OS 
LOAD CSVC) simulation command. This 05 LOAD comnand increments a 
pointer CLOCCNT) in HUCOH to the next available location in 
GETMAIN storace. If you then leave APL, the LOCCHT pointer is not 
reset. The STRIHIT macro then resets GETMAIN storage based on thea 
LOCCHT pointer. Consequently, the next time you enter APL, your 
available GETIMAIM storage will have bean decreased by the amount 
of storage used by the AP invoked by APHAMES. 


However, aven if you have not modified the APLEXIT exec, you will 
reset the LOCCHT pointer and thus avoid the potential storage loss 
if you have performed one of the following actions between 
entering and leaving APL: issued a CMS LOAD command, isseada 
LOARTIOD command, or invoked a nontransient module. Tha APLEXIT 
exec, once it has been modified as described above, achieves the 
same result by issuing a LOAD command each time you leave APL. 


For more information about CNS storage handling, see IBM Virtual 
Machine/System Product: Svstem Programmer's Guide. 


For more information on specifying VS APL options when invoking VS 
APL, see VS APL for CHS: Terminal User's Guide. 
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VS APL for CMS: 


Both project and public libraries contain workspaces that are CMS 
files with filetypes of Honnnnnn, Cwhere nonnnnn is the library 


number). For example, public library tiorkspace 1 HEMS is a ChiS 
file with a filename of NEHS and a filetype of WO000001. 


Any user can access the workspaces ina public library; however, 
only VS APL users who know the project library disk's read 
password can access project library workspaces. For information 
on which commands VS APL users can issue, see the section 
"Maintaining Public and Project Libraries." 


The CMS file APLIBTAB APLIBTAB defines private, project, and 
public libraries. To create new libraries, add entries to 
APLIBTAB, as dascribed in this section. Entries to APLIBTAB must 
begin in column one, and may not be more than one line. Separate 
operands with one or more blanks. VS APL users should have access 
to a copy of APLIBTAB, either on their A-disk or on any other 
accessed minidisk. 


Workspaces added to libraries on a CMS minidisk not formatted with 
an 800-byte block size are written with a record length of 80 
bytes. 


When creating VS APL Libraries, use the numbers 1 to 33 to define 
public libraries and any number greater than 1001 Cbut not more 
than seven digits) to define project libraries. VS APL uses the 
number 1001 to define private libraries. 


Bo not define libraries with the numbers 100 to 4993; those numbers 
are reserved for auxiliary processors supplied with VS APL. 
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CREATING A PRIVATE LIERARY 


Library 1001 is defined as each user's private library in 
APLIBTAB. 


To create a private library in addition to the default: 


1. 


Add an entry to APLIBTAB. A private library entry has the 
format: 


PRIVATE libnum|C(first-libnum last-libnum) 
owner device a filemode 


ee 


where 


PRIVATE 
is the library type. Only the first three letters are 
required. 


Llibnum 
is the library number. It can be any positive integer not 
defined for an auxiliary processor Cany number greater 
than 1001 1s recommended), but no greater than seven 
digits. 


Cfirst-libnum last-libnum) 


156 a range of library numbers; the first number must be 
less than or equal to the second number. 


eo] 


wner device 
is the user identification of the owner and the virtual 
device address of the private library disk. 


| 


a filemode 
designates that the library libnum is on the minidisk 
filemode. If the minidisk is not accessed by the VS APL 


user, the library libnum is unavailable. 
For example, to define a private library with a library number 
of 1003 for any VS APL user who has access to the minidisk G, 
add the entry: 
PRIVATE 1003 a G 


To create a private library with a library number of 1002 and 
device address 131 for VS APL user VUSER, add the entry: 


PRIVATE 1002 VUSER 191 


Add workspaces by using VS APL commands. For information on V5 
APL commands, see VS APL for CMS: Terminal User's Guide. 


CREATING A PROJECT LIBRARY 


To create a project library: 


Ls 


Add an entry to APLIBTAB. A project library entry has the 
format: 
PROJECT libnum|(first-libnum last-libnum) owner device 
Cmode] 
where 


PROJECT 
is the library type. Only the first three letters are 
required. 


libnum 


is the library number. It can be any positive integer not 
defined for an auxiliary processor Cany number greater 
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than 1001 is recommended), but no greater than seven 
digits. 


Cfirst-libnum last-libnum) 
is a range of library numbers; the first number must be 
less than or equal to the second number. 


owner 
is the identification of the owner of the project 
library disk. 


device 
is the virtual device address of the project library 
disk in the disk owner's directory. 


mode 
is the access mode when writing to the disk; the default 
is W (write-access). 


For example, to create a project library that is owned by the 
CMS user with the identification of APLPROJ and is on 
APLPROJ's 197 disk, and has a library number of 4000, use the 
CMS editor to add this record to APLIBTAB: 


PROJECT 4000 APLPROJ 197 
Define the CMS minidisk for project libraries. 
The procedure for defining a minidisk is described in IBM 


Virtual Machine Facility/370: Planning and System Generation 
Guide. When defining a project library minidisk, observe 


these guidelines: 


e Define a minidisk in a user directory entry that is used 
for no other purpose than to contain the definition of the 
project library disk. This is recommended because VS APL 
links to a project library disk dynamically and cannot do 
so if a permanent link exists. If the disk is defined in 
an active user directory entry, it must be detached each 
time the user logs on. 


e For maximum security, define a project library ona CMS 
minidisk that is used only to contain project libraries. 
Under CMS, passwords are defined for an entire minidisk, 
rather than for each file. 


e Define passwords to impose the desired level of control. 
To allow uncontrolled access, define a password of ALL. 


CREATING A PUBLIC LIBRARY 


36 


VS APL for CMS: 


Public libraries 1 to 99 are defined in APLIBTAB; you can add new 
public library numbers or change the numbers of existing 
libraries. 


To create a new public library: 


1. 


Add an entry to APLIBTAB. A public library entry has the 
format: 


PUBLIC libnum| (first-libnum last-libnum) 
C[filemode] 


where 


PUBLIC 
is the library type 


libnum 
is a library number; it can be any positive integer other 
than 1001 C€the numbers 1 to 99 are recommended), but no 
greater than seven digits. 
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(first-libnum last-libnum) 


is a range of library numbers; the first number must be 
less than or equal to the second number. 


filemode 
is a single letter that identifies the minidisk on which 
the public library or range of libraries is located. If 
omitted, Y is assumed. 


For example, if you want to create a public library witha 
library number of 939 on your Fr-disk, use the CMS editor to add 
this entry to APLIBTAB: 


PUBLIC 99 F 


2. Add workspaces to the library by using VS APL commands. (See 
the section "Maintaining Public and Project Libraries" for 
how to use VS APL and CNS commands to add and delete library 
workspaces. ) 


To change the numbers assigned to existing public libraries, 
modify APLIBTAB entries. For example, to redefine public 
libraries 1 through 5 as libraries 6 through 10, use the CMS 
editor to change the entry: 

PUBLIC (1 5) Y 

to 


PUBLIC (6 10) Y 


MAINTAINING PUBLIC AND PROJECT LIBRARIES 


Only a VS APL user with write access can delete, replace, or save 
workspaces ina public or project library. Any VS APL user can 
access Workspaces in a public library; only VS APL users who know 
the read password for a project library minidisk can access 
workspaces ina project library. 


To add or replace a workspace to a project or public library: 
1. Have the VS APL user who created the workspace send it to you: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 


where 


userid 
is your user identification. 


filename filetype 
is the workspace identification. 


You can also have it sent to you with the CMS PUNCH command if 
the workspace has a record length of 80 bytes. 


SPOOL PUNCH userid 
PUNCH filename filetype 


where 


userid 
15 your user identification. 


filename filetype 
is the workspace identification. 


2. Transfer the workspace from your virtual reader to your 
A-disk. 
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VS APL for CMS: 


If the VS APL user specified DISK DUMP to send the file to 
you, use the command: 


DISK LOAD 
If PUNCH was specified, use the command: 
READCARD X* X 


3. Access the library disk for read/write, with any filemode (B 
is used in the following example): 


CP LINK userid vaddrl vaddr2 mode 
ACCESS vaddr2 B 


where 

userid 
is the identification of the directory to be searched 
for the device vaddrl. 


vaddril 
is the virtual device address in the directory. 


vaddr2 
is the virtual device address that is to be assigned to 
the minidisk. 


mode 


is W Cwrite-access). 


4. Copy the workspace from your A-disk to the library disk. For 
example: 


COPYFILE NEWPUB VSAPLWS A = WO0000003 B CREPLACE 


Specify the REPLACE option only if the workspace is intended 
to replace one with the same identification. Rename the 
workspace by using the CMS COPYFILE command, as shown in the 
previous example, or do the following: 


a. Invoke VS APL. 


b. Load the workspace into your active workspace. For 
example: 


)LOAD NEWWS 


c. Add the workspace to the public or project library, 


changing the filetype to the library number. For example: 


)SAVE 3 NEWWS 


To delete a workspace from a public or project library, either 
access the library disk for read/write, and issue: 


)DROP 3 NEWWS 
Or the CMS ERASE command: 
ERASE filename filetype filemode 


where 


filename filetype 
is the workspace name and number. 


filemode 
identifies the library disk. 


For information VS APL commands, see VS APL for CMS: Terminal 
User's Guide. 
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TRANSPORTING WORKSPACES AND VS APL DATA FILES 
This section explains how to transfer workspaces and VS APL data 
files to and from direct access storage. You can transport 
Workspaces and VS APL data files out of CMS by transferring them 
from VS APL libraries to tape. The tape can then be sent to 
another CMS installation, or to a CICS/VS, TSO, or VSPC 
installation. 


You can transport workspaces and VS APL data files in to your VS 
APL system by obtaining a tape from another CMS installation, ora 
TS0, CICS/VS, or VSPC installation, and transferring the 
Workspaces and files on the tape into VS APL libraries. For more 
information about exporting VS APL data files to CNS from CICS/VS 
or VSFC, see VS APL for CICS/VS: Installation Reference Material 
or VS APL for VSPC: Installation Reference Material. 


You can use the same CMS commands to transport VS APL data files 
and workspaces. However, VS APL data files have different 
attributes from workspaces, so you should be careful to specify 
the correct record format and record length. 


Direct VS APL data files have fixed record formats, with record 
lengths of up to 4054 bytes. Sequential VS APL data files have 
variable record formats, with record lengths of up to 4074 bytes 
per CMS block. The actual VS APL object can be longer and is 
written in as many CMS blocks as required. 


TRANSPORTING IN TO CNS 
At the CMS installation: 


1. Ask the system operator to mount the tape and to attach the 
tape drive as virtual device 181, 182, 183, or 184%. 


2. Access for read/write the minidisks to which the workspaces 
or VS APL data files will be transferred. 


3. Define the input device by issuing the CMS FILEDEF command. If 
you are transferring workspaces, issue the following command: 


FILEDEF INMOVE TAPn CRECFM F LRECL 800 BLOCK 800 


where n is l, 2, 3, or 4 to represent device 181, 182, 183, or 
184. 


You can also use the FILEDEF command to define the output 
device when transporting VS APL data files. For example, to 
define an output device for a direct file with a record length 
and block size of 132, issue the command: 


FILEDEF INMOVE TAPn CRECFM F LRECL 132 


where nis l, 2, 3, or ¢ to represent device 181, 182, 183, or 
184. 


4. Transfer the workspaces or VS APL data files from tape to disk 
by issuing these CMS commands for each: 


FILEDEF OUTMOVE DISK filename filetype filemode 
MOVEFILE 


where 


filename 
is the name of the workspace or library. 


filetype 
is VSAPLWS if the workspace is transferred to a private 


library; it is Wnnnnnnn if the workspace is transferred 
to a public or project library, where nnnnnnn is the 
library number. 
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VS APL for CMS: 


At the CMS installation: 


I 


Have the system operator mount a scratch tape and attach the 
tape drive as virtual device 181, 182, 183, or 184. 


Access for read/write the minidisk to which the workspaces 
will be transferred. 


Define the output device with the CMS FILEDEF command. When 
transporting workspaces, issue the command: 


FILEDEF OUTMOVE TAPn CRECFM FB LRECL m BLOCK 800 
where 
n 


is 1, 2, 3, or & to represent device 181, 182, 183, or 
184. 


I5 


can be either 890 or 800, depending on the record length 
of the file. 


Use the FILEDEF command to define the output device when 
transporting VS APL data files. For example, to define a 
sequential file with a variable-length record format and a 
maximum record length of 512, issue the command: 


FILEDEF OUTMOVE TAPn CRECFM V LRECL 512 


Where nisl, 2, 3, or 4 to represent device 181, 182, 183, or 
184. 


Transfer the workspaces and VS APL data files to tape by 
issuing these CMS commands for each: 


FILEDEF INMOVE DISK filename filetype filemode 
MOVEFILE 


where 


filename filetype filemode 


is the CHS identification of the workspace. 


When all workspaces have been transferred to tape, rewind and 
unload the tape: 


TAPE RUN CTAPn 
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APPENDIX A. VIRTUAL STOPAGE REQUIREMENTS 


The virtual storage estimates in this appendix are based ona VS 
APL system with: 


e One user having a workspace size of 96K bytes. 


° All the auxiliary processors available, but not being used. 
(Use of the auxiliary processors increases the virtual 
storage estimates depending on which auxiliary processors are 
used. For example, using the APL Data File auxiliary 
processor under CHS requires additional virtual storage for 
each record processed; the amount of additional virtual 
storage depends on the size of the APL object.) 


Figure 10 shows the minimum virtual machine size required to 


install and execute VS APL for each user, and to execute the 
conversion programs. 


Subsystem To Install To Execute To Exnccute Cenversicn Preeresns 


Nonshared VS 1 Megabyte 1 Megabyte 200K + 3.1 x WS? for APLCVCMS 
APL 200K + 2.1 x WS? for APLCVRPQ 


Shared SSA! + 512K 512K as above 
VS APL + GOO0K Cshared 
main storage) 


Figure 10. Virtual Storage Requirements 


Notes to Figure 10 


1 SSA 185 the shared system's load address. 


2 WS is the size of each APL workspace. 


3 WS is the size of the largest APL workspace. 


Space requirements for other products, such as GDDM, are not 
included. 
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APPENDIX B. AUXILIARY STORAGE REQUIREMENTS 


You need the following auxiliary storage to install VS APL: 
° 3 megabytes on your A-disk 


e 2 megabytes on your Y-disk 
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The following terms are defined as they 
are used in this book. If you do not find 
the term you are looking for, see the 
index, or the IBM Data Processing 
Glossary, GC20-1699. 


A-disk. In CNS, a user's primary disk; 
accessed for read/write when a CMS 
tarminal session 15 begun. 


AFLIBETAB. Formerly called the VS APL 
library table file. Defines private, 
public, and project libraries to VS APL. 


content conversion. A type of workspace 
conversion in which the contents of a 
workspace are analyzed and modified. A 
list of functions that may not execute 
properly under VS APL 1s included in the 
conversion report. (See also format 
conversion. ) 


conversion pragram. Under CNS, the 
APLCVCHS proaram, which converts APLN360 
and APLSV workspaces, or the APLCVRPQ 
program, which converts APL/CHS 
workspaces. 


conversion report. A report that is 
produced by the conversion procedure. It 
lists information about the conversion 
process. 


customize. To enhance or extend an IBM 
program by using services and built-in 
facilities provided by IBM for that 
purpose. 


executor. The component of VS APL that 
provides environment-dependent services 
for the interpreter. 


filesode. The third field of a CMS file 
identification. It identifies the 
minidisk on Which the file resides. 


filenazre. The first field of a CMS file 
identification. VS APL workspaces have 
filenames that are the same as their 
Workspace names. 


filetype. The second field of a CMS file 
identification; it may implicitly define 
certain file characteristics. Private 
library Workspaces all have the same 
filetype; project and public library 
Workspaces have a filetype of the letter 
W followed by a 7-digit library number. 


format conversion. A type of conversion 
in which workspaces are modified so that 
they will execute under VS APL. Functions 
that may not execute under VS APL are not 
converted to their VS APL equivalent. 
(See also content conversicn. ) 


full conversion. Workspace conversion 
in which all input workspaces are 
converted. (See also selective 
conversion. ) 


install. To make a program ready to do 
useful work. Includes generating a 
program, initializing it, and applying 
PTFs to it. 


interpreter. The component of VS APL 
that scans, analyzes, and executes VS APL 
statements. 


private library. A set of stored 
workspaces available to a specific VS APL 
user. 


project library. A set of stored 
workspaces that can be shared among a 
selected set of VS APL users. 


public library. A set of stored 
Workspaces available to all VS APL users. 


resource definition. The process of 
defining to the system those items users 
need to complete tasks. 

session log. (See VS APL session log.) 
selective conversion. Workspace 
conversion in which only specified input 
workspaces are converted. (See also full 
conversion. ) 


session manager. (See VS APL session 
manager. ) 

session manager profile. (See VS APL 
session manager profile.) 


shared stcrage manager. The component of 
VS APL that manages the communication 
between auxiliary processors. 


system disk. The disk that contains the 
CMS nucleus and disk-resident command 
modules; accessed for read-only when a 
CMS terminal session 15 begun. 


VS APL session log. A record of a user's 
dialog with VS APL; analogous toa 
console log. 


VS APL session manager. A component of 
VS APL that provides full-screen 
interaction with VS APL. It produces a 
log of your VS APL session, enables you 
to scroll through that log, and provides 
a set of commands for controlling your VS 
APL session. 


VS APL session manager profile. The file 


which contains settings for the VS APL 
5ess10n manager. 
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Workspace. The structure in which data, 
programs, execution status, and other 
information required by APL are stored. 
You have one active workspace while 
Signed onto VS APL, and a number of saved 
workspaces. Only your active workspace is 
immediately available. To use a saved 
workspace, you must load it to make it 
active. 


workspace identification. Consists of 
the library number of the workspace and 
the workspace name. 


Y-disk. In CMS, A disk that is an 
extension of the system disk. It contains 
VS APL modules, procedures, and public 
libraries. 
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YDROP command 38 
YLOAD command 13, 38 
YSAVE command 38 
IWSID command 38 


A-disk 
during installation 
accessing & 
checking files on 9 
formatting 8&8 
adding VS APL users) 32 
Alternate Input auxiliary processor 
AP 100 33 


AP 110 33 
AP 111 33 
AP 120 33 
AP 121 33 


AP 121 files 
See APL data files 
AP 123 33 
AP 126 33 
APL data files 
format of 39 
note on terminology v 
transporting 
in to CHS 39 
out of CMS 40 
APL options 
parameters 
CMSCMD 5 
FRMIN 6 
FRSIZE 6 
GDDM 5 
GDMPRTY 7 
MMDDYY 7 
PRIVFIL 5 
PRIVPRO 6 
PRIVWS 5 
REL 5 
RESAPS 7 
SHMIN 6 
SHSIZE 6 
SMSIZE 6 
WSMIN 6 
WSSIZE 6 
specifying 
after installation 17 
during installation 9 
APL/CMS workspaces, converting 
for use under CMS 
changing converted workspace 
identification 27 
distributing 27 
for use under VSPC or CICS/VS 
distributing 28 
program for 23 
APLACMD macro 15 
APLACMSG module 15 


33 


APLAMSG MACRO 16 
APLCVCMS conversion program 
invoking 23 
options 23 
APLCVRPQ conversion program 
invoking 23 
options) 23 
APLEXIT exec 
modifying 17, 34 
using to define GDDM as a nonshared 
system 13 
APLIBTAB 
definition of 34, 43 
PRIVATE entry in 35 
PROJECT entry in 35 
PUBLIC entry in 36 
APLINSTL command 10 
APLINSTL EXEC 93 
APLN360 workspaces, converting 
changing converted workspace 
identification 27 
distributing for use under CMS 27 
program for 23 
APLSCLNK exec 33 
APLSCSNT module 3, 12 
APLSV workspaces, converting 
changing converted workspace 
identification 27 
distributing for use under CMS 27 
program for 23 
APNAMES invocation option 17, 33 
auxiliary processors 
defining 32 
list of 33 
suggested numbers for 32 
auxiliary storage requirements 42 
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CMS File auxiliary processor 33 
Command Processor auxiliary 
processor 33 
CONTENT conversion option 23 
conventions for syntax notation v 
conversion messages 29-31 
conversion programs 
APLCVCMS 18, 23, 41, 43 
APLCVRPQ 18, 23, 41, 43 
converting workspaces 
accessing the A-disk 23 
converted workspace identification 
changing 26 
recognizing 26 
distributing workspaces, for use 


under 
CICS/VS 28 
CNS 27 
TSO 29 
VSPC 28 
input 19 


invoking the conversion program 
for APL/“CMS workspaces 23 
for APLSV or APLN360 
workspaces 23 


Index 
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logging on 23 
messages 29-31 
mounting the conversion tape 23 
options 23 
overview of procedure 19 
planning for 18-19 
restarting the conversion program 25 
at the end of tape 25 
because of unexpected 
termination 25 
using the conversion program 
changing duplicate file 
identification 25 
changing invalid workspace 
indentification 25 
specifying workspace names and 
library numbers 24 
terminating 25 
using EBCDIC characters instead of 
APL 24 
creating libraries 34-37 
customizing VS APL 
modifying the APLEXIT exec 17 
redefining VS APL characters for 
hardcopy 14 
5e5510n manager 15, 16 
changing the text of messages 15 
defining synonyms for commands 15 
modifying default profile 16 
Specifying VS APL options 17 
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default profile 16 
DEFAULT VSAPLPR 16 
defining resources for VS APL 
auxiliary processors 32 
maintaining libraries 37 
private libraries 
creating 35 
definition of 43 
PRIVATE entry in APLIBTAB 35 
project libraries 
creating 35 
definition of 34, 43 
PROJECT entry in APLIBTAB 35 
public libraries 
creating 36 
definition of 34%, 43 
PUBLIC entry in APLIBTAB 36 
transporting workspaces and VS APL 
data files 
description of file formats 39 
in to CMS 39 
out of CMS 40 
VS APL users) 32 
deleting workspaces 38 
directory entry 
guidelines for defining 32 
drop command 38 
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EBCDIC characters 24 
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Fonts, 3800 printer 12 
FULL conversion option 23 


Graphical Data Display Manager 
as a software requiremant for 
installation 3 
defining as nonshared 13 
specifying whether shared or 
nonshared 5 
Graphical Data Display Manager auxiliary 
processor 33 
GRAPHPAK 
installing 12 
requirements for installation 4% 
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hardcopy translation table 1% 
hardware requirements for installing VS 
APL 3 


[| 


IMPORT COMMANDS 
format of 28 
modifications to 29 
IMPORT DDCARDS 
format of 28 
modifications to 28 
installation, planning for 
See planning for installation 
installing VS APL 
APLINSTL EXEC 9 
checking the files on the A- and 
Y-disks 9 
copying APL execution files 13 
defining GDDM as nonshared 13 
defining, loading, and saving a shared 
system 
GRAPHPAK 12 
hardware requirements) 3 
logging on 8&8 
mounting the tape 9 
overview of the procedure 8 
Planning for 7 
software requirements 3 
3800 printer fonts 12 
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invalid for conversion 18 
valid for project libraries 34 
valid for public libraries 34 
load addresses for shared VS APL 2 
LOAD DMSZIT command 34 
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macros 
APLACMD 15 
APLAMSG 16 


maintaining libraries 
adding workspaces 37 
deleting workspaces 38 
messages 
conversion 29 
note on v 
VS APL session manager, changing the 
text of 16 
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NAMESYS macro 11 
NOCONTENT conversion option 23 
nonshared VS APL 
compared with shared VS APL 1 
virtual storage requirements) 41 
notation, syntax v 
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options 

conversion 
CONTENT 23 
default 24 
FULL 23 
NOCONTENT 23 
RESUME 23 
SELECT 23 

VS APL 
overview 4-7 
specifying 17 
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planning for converston 
auxiliary storage requirements 
APL/CMS workspaces for use under 
CICS/VS, VSPC, or TSO. 18 
APL/CMS, APLN360, APLSV 
workspaces 18 
invalid library numbers and workspace 
names 18 
planning for installation 
rt ee eels of shared and nonshared V§ 
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defining a load address for a shared 
system 2 
hardware requirements 3 
software requirements) j3 
private libraries 
creating 35 
definition of 43 
entry in APLIBTAB 35 
numbering 34 
project libraries 
creating 35, 36 
defining minidisk for 
guidelines 36 
security 36 
definition of 34, 43 
entry in APLIBTAB 35 
maintaining 
adding workspaces 37 
deleting workspaces 38 
numbering 34 
public libraries 
creating 36 
definition of 34, 43 
entry in APLIBTAB 36 
maintaining 
adding workspaces) 37 
deleting workspaces 38 
numbering 34 
publications 
related iv 
required iii 
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REGEN installation option 10 
RESUME conversion option 23 


save command 38 
saved segment names for shared VS APL 2 
SELECT conversion option 23 
session manager 
changing the text of messages 15 
defining synonyms for commands 15 
definition of 43 
description of 14 
session manager default profile 16 
shared VS APL 
compared with nonshared VS APL 1 
defining, loading, and saving 11 
load address 2 
virtual storage requirements 41 
software requirements for tnstalling VS 
APL 3 
storage requirements 
auxiliary 42 
virtual 
to execute the conversion 
programs 41 
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